home *** CD-ROM | disk | FTP | other *** search
/ MacWorld 1997 August / Macworld (1997-08).dmg / Shareware World / Info / For Developers / InstallerMaker™ 4.0 Installer / Customizing InstallerMaker / Sample Code / Serialization Example / v1.1.1 Read Me < prev    next >
Text File  |  1997-05-12  |  11KB  |  151 lines
  1. Serialization Module 1.1.1
  2. Extension for InstallerMaker v4.x
  3.  
  4. The Serialization Module is designed to be an easy to use plug-in for Aladdin's InstallerMaker 4.x series, that gives developers a simple means of software protection, by soliciting registration information from the user prior to installation. Further, there is the option to record this information into installation files, and an option to encrypt that information, giving added software protection.
  5.  
  6. In order to use this module, it is assumed that you understand how to use InstallerMaker and are comfortable using ResEdit.  The options to save user registration information into files, with or without encryption, will require that you have sufficient programming skills to make use of that information once it is saved.
  7.  
  8. The Serialization Module is designed to be compatible with System 6.0.4 and greater, but has not been tested under System 6, so be sure and test it under System 6 if your installer will be going out to System 6 users.
  9.  
  10. This module is free for public use, but not public domain.  ©1996 Aladdin Systems, Inc..
  11. Use of this module is granted providing that Aladdin, Eric Long, and anyone else associated with the production of this module are held free from liability and all associated risk, direct or indirect, associated with this module and its use.
  12.  
  13. Fixed in 1.1.1:
  14. • Failure to initialize abort parameter caused installation to abort in some instances. The abort parameter is now initialized properly.
  15.  
  16. New in 1.1:
  17. • Now passes all user information to custom verification procedure
  18. • New encryption algorithm gives better protection.
  19.      Note: The new encryption routine is not compatible with the v.1.0 routine.
  20. • Now lets you add your own custom encryption procedure.
  21.  
  22. What the module is:
  23.  
  24. The Serialization Module is a resource file you include with your installer, which contains two InstallerMaker extensions:  an 'IBeg' called GetSerialNum, and an 'IMid' extension called PersonaliseFile.
  25.  
  26. GetSerialNum 'IBeg'
  27.  
  28. This extension posts a dialog at the beginning of installation, prior to any files being installed.  The dialog asks the user to enter a name, organization and registration number, in order to register the software being installed.
  29.  
  30. You may customize this dialog, if needed, by adding static text, PICT, or ICON items.  The static text items already in place may be edited to show different text.  Do not remove existing items, change their item types, or their item numbers; this would likely result in a system crash.
  31.  
  32. The registration number, or serial number, must match a pre-set format, which you can customize with ResEdit.  A 'Form' resource included in the "Serialization Package.rsrc" file contains the format string used, and the included custom template makes editing simple.
  33.  
  34. The format string may contain: uppercase letters, numbers and the dash character (-).
  35.  
  36. The # symbol designates where a number is expected.
  37. The $ symbol designates where a letter is expected.
  38. The - symbol designates where a dash is expected.
  39.  
  40. The default format string is:  #$#-$##$-#$#
  41. Example registration number meeting that format: 1A1-A11A-1A1
  42.  
  43. The format string must not exceed 30 characters.
  44.  
  45. A custom verification procedure may also be used in addition to checking the format string.  GetSerialNum looks for a code resource of type 'Auth', with ID# 3100.  If a code resource is found, it calls the code, passing it the user's registration information for verification.  See "Implementing A Custom Verification Procedure" below for more details.
  46.  
  47. The 'Form' resource also contains two other settings you may want to use:
  48.  
  49. 1. You can choose to save the user's name, organization and registration number into files that are installed.
  50.  
  51. 2. You can choose to have that information saved in an encrypted format.
  52.  
  53. You can choose the default encryption routine, or create your own.  See "Implementing A Custom Encryption Procedure" below for more information.
  54.  
  55. Example code is provided in the file "GetUserInfo.c" within the Serialization Project Files folder, to show you how to retrieve the user registration information from installation files.
  56.  
  57. If the user does not provide a correct registration number, installation is aborted and an alert is posted, telling the user that your software must be registered before it may  be installed.
  58.  
  59.  
  60. PersonaliseFile 'IMid'
  61.  
  62. This extension will record the user's registration information into installation files that have been tagged in the installation archive in InstallerMaker with the hexadecimal number 5057, when you choose the save option in the 'Form' resource.  50 is the character code for the letter P and 57 is the code for W, so you can think of the tag as marking the file with PW, as in "password".  To place this tag on a file, select the file in InstallerMaker and then select "Get Info" from the Archive menu.  In the dialog that comes up, enter 5057 at the bottom, next to where it says, "Data Tag."  Make sure Hex is selected in the popup menu next to it.
  63.  
  64. The user's registration information will be saved into a 'RVal' resource, a.k.a. "Registration Validation" information.
  65.  
  66. Format of the 'RVal' resource:
  67.  
  68.  typedef struct{
  69.      Str31        serialNumber;
  70.      Str255        userName;
  71.      Str255        organization;
  72.  } SerialInfo, *SerialInfoPtr, **SerialInfoH;
  73.  
  74. If you also choose to encrypt this resource, the DecryptInfo() routine in the "GetUserInfo.c" file may be used to read the data correctly.
  75.  
  76.  
  77. How to include the Serialization Module in an installer…
  78.  
  79. First, make a copy of the file named Serialization Package.rsrc, included in this package.  In the archive window of your installer, you will notice a tiny "Jack-in-the-Mac" icon, usually associated with ResEdit.  Click on this icon and InstallerMaker will ask you to select a resource file to include: Select the copy you made of the Serialization Package.rsrc file.  (You should never use the original, first, because you will need to customize the copy you use, and second because it is much safer to keep the original untouched, so you can revert back to it if something undesirable should happen to your copy.)
  80.  
  81. Prior to building your installer, open your copy of the Serialization Package.rsrc file with ResEdit.  Open the 'Form' resource and change the format string to one that fits your needs (do not exceed 30 characters).  Set the option for saving the registration information into installation files and the encryption option as suits your needs.  If you choose not to save any information into installation files, the PersonaliseFile 'IMid' resource may be removed from the resource file.
  82.  
  83. The 'Form' resource template:  You may want to copy this template and paste it into your ResEdit preferences file.  (If needed, the ID number of the template may be changed.  This will not effect its usage.)  You should delete the template from the resource file you include with your installer, prior to building the installer.  This will make it more difficult for snoops with a copy of ResEdit to hack the 'Form' resource in your installer.
  84.  
  85.  
  86. Implementing A Custom Verification Procedure
  87.  
  88. If you would like to implement a registration verification procedure of your own, you will need to write your own code resource to handle this procedure.
  89.  
  90. The GetSerialNum 'IBeg' will call your procedure only if the registration number entered by the user first matches the format expected.
  91.  
  92. Your main() function should look like this:
  93.  
  94. pascal short main( SerialInfoPtr *userInfo );
  95.  
  96. userInfo  is a pointer to a SerialInfo struct holding the registraton information entered by the user.  This struct is the same used in the 'RVal' resource, as shown above.
  97.  
  98. You should return 1 if the registration is ok, and 0 if it is not ok.
  99. Build your code resource with the type 'Auth' and the ID# 3100.
  100.  
  101.  
  102. Implementing A Custom Encryption Procedure
  103.  
  104. If you would like to implement a custom encryption procedure, in place of the default procedure, you will need to write a code resource to handle it.
  105.  
  106. If "Encrypt Info" is set to true in the 'Form' resource, the GetSerialNum 'IBeg' first checks for a code resource of type 'GRbl' (as in "garble") with the ID# 3100.   If it is found, the code resource is called in place of the standard encryption routine.
  107.  
  108. Your main() function should look like this:
  109.  
  110. pascal void main( SerialInfoPtr *userInfo);
  111.  
  112. userInfo  is a pointer to the same struct used in the 'RVal' resource, as stated above.
  113.  
  114.  
  115. Using The Source Code
  116.  
  117. The Serialization Project Files folder, included in this package, contains the source code and resource files used to generate the Serialization Module.  You may use this code freely in your own applications, as outlined in the terms specified below and in the source files.
  118.  
  119.  
  120. This module was written by:
  121.  
  122. Created by Eric Long
  123. Developer Technical Support/Product Quality Validator
  124. Aladdin Systems, Inc.
  125.  
  126. Internet: ericsmac@aladdinsys.com
  127.  
  128. *******************************************************************************
  129. **                      L E G A L   N I C E T I E S
  130. *******************************************************************************
  131.  
  132.     This source code is (c) 1997 Aladdin Systems, Inc.  You are free to use it 
  133.     in connection with your own products and distribute it in either source code 
  134.     or object code form.  However, this source code and accompanying written 
  135.     materials (including instructions for use) are provided "as is" without 
  136.     warranty of any kind.  Further, Aladdin Systems does not warrant, or make 
  137.     representations regarding the use, or the results of the use, of the source 
  138.     code or written materials in terms of correctness, accuracy, reliability, 
  139.     currentness, or otherwise.  No oral or written information or advice given 
  140.     by Aladdin Systems or its employees shall create a warranty, and you may not 
  141.     rely on such information or advice.
  142.     
  143.     Neither Aladdin Systems nor anyone else who has been involved with the 
  144.     creation, production, or delivery of the source code shall be liable for 
  145.     any direct, indirect, consequential, or incidental damages (including damages 
  146.     for loss of business profits, business interruption, loss of business 
  147.     information, and the like) arising out of the use or the inability to use the 
  148.     source code even if Aladdin Systems has been advised of the possibility of 
  149.     such damages.  Because some states do not allow the exclusion or limitation 
  150.     of liability for consequential or incidental damages or the limitations of 
  151.     duration of implied warranty, the above limitations may not apply to you.